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1 Introduction 


Technological innovations have been driving progress in neuroscience while tools for 
measuring, describing and quantifying behavior lagged behind. There is currently no 
standardized framework for designing and archiving behavioral aspects of neuroscience 
experiments. Without appropriate formal description, behavioral tasks are difficult to 
communicate precisely or extend to different systems, which impedes the sharing and 
reproducibility of behavioral neuroscience. 


We propose BEADL (behavioral task description language) to standardize the design and 
the description of behavioral experiments based on the extension of so-called finite-state 
machines. BEADL describes behavioral experiments on a higher abstraction level, there- 
fore its implementation is hardware-independent and suits a wide variety of trial-based 
behavioral experiments. Because of the formal structure of finite-state machines, a task 
description using BEADL can be compiled into hardware-specific source code to be exe- 
cuted in different real-time environments. 


In its current version, BEADL is implemented as a markup language using an XML (eX- 
tensible Markup Language) approach. This ensures a somewhat rigid yet extensible 
framework to meet the requirements of different control systems for behavioral neuro- 
science experiments. Furthermore, the future use of either a Document Type Definition 
(DTD), XML Schema Definition (XSD), or other schema language technologies for XML 
like RELAX NG ensure the formal verification of the content of an XML-based BEADL 
file. 


2 XML Element Overview 


Since BEADL is implemented using XML, there should only be a single root element 
(Beadl) in the structure of a well-formed BEADL file. Under this root element two 
different child elements are currently designated, describing the trial-based protocol 
implementation (BeadlTrialProtocol) and properties for a future (graphical) editor 
(BeadlEditor). Under the Bead1TrialProtocol node, all properties of the actual protocol 
implementation as well as hardware-specific attributes are gathered together. A 
separation of hardware-specific attributes should facilitate a change of the used hardware 
platform, so a change does not interfere with the actual protocol implementation and 
interpretation. 


2.1 Beadl root element 


The root element Beadl in the XML format works as a container for the behavioral task 
protocol definition but also to non-protocol specific properties such as properties for a 
graphical representation of the protocol in an additional editor. 


The basic structure of a BEADL file looks like this: 


<?xml version="1.0" encoding="UTF-8" ?> 
<Beadl version="0.1"> 
<BeadlTrialProtocol name="DummyTask" startState="InitTrial" numberOfTrials="Inf"> 


</BeadlTrialProtocol> 
<BeadlEditor> 


</BeadlEditor> 





2.1.1 Attributes 


In the current implementation, the Beadl root element has only one attribute version 
which defines the version of the BEADL implementation being used in that file. 


2.1.2 Child elements 


The Beadl root element must have only one BeadlTrialProtocol child and one 
BeadlEditor child as sub-elements. These and their associated attributes and child 
elements are described in their own section. 


2.2 BeadlTrialProtocol element 


The BeadlTrialProtocol element describes and implements all properties of the trial- 
based behavior protocol. 


The element itself has the following attributes: 


e name: Defines the name of the protocol 


The name of the protocol will be used during the code generation for creating 
needed files and folders - at least in the Bpod implementation of BEADL —- and 
thus should not contain any whitespaces. In the example above this attribute has 
the content DummyTask. 


e startState: Defines the starting point of the trial structure 
The content must refer to one state listed later in the description. In the example 
above this state would be called InitTrial. 

e numberOfTrials: Defines how many trials a session should last 


The content of this attribute can either be a number (must be quoted!) or the string 
literal Inf to indicate that the session will not be terminated based on the number 
of performed trials. 


! XML requires all attribute values to be encapsulated by either single or double quotes 


The following listing shows an example for a protocol implementation: 


<?xml version="1.0" encoding="UTF-8"?> 
<Beadl version="0.1"> 
<BeadlTrialProtocol name="SimpleExample" startState="startState" numberOfTrials="Inf"> 
<BeadlArguments> 
<BeadlArgument name="valveTime" type="numerical" /> 
</BeadlArguments> 
<HardwareSettings hardware="Bpod" version="@.5" lang="MATLAB"> 
<ConnectionMapping name="rewardPort" resource="Port1i" type="port"> 
<Value /> 
<Dependency /> 
</ConnectionMapping> 
</HardwareSettings> 
<BeadlInputs> 
<HardwareInput name="rewardPortPoke" type="in/out" connection="rewardPort.poke" /> 
</BeadlInputs> 
<BeadlActions> 
<HardwareAction name="rewardPortLED" type="led" connection="rewardPort.led" /> 
<HardwareAction name="rewardPortValve" type="valve" connection="rewardPort.valve" /> 
</BeadlActions> 
<Bead1States> 
<Bead1lState name="startState"> 
<StateTimer>@</StateTimer> 
<StateOutputActions> 
<OutputAction action="rewardPortLED" >on< /OutputAction> 
</StateOutputActions> 
<StateEvents> 
<ExternalEvent source="rewardPortPoke" eventname="rewardPortiIn">in</ExternalEvent> 
</StateEvents> 
</Bead1State> 
<Bead1lState name="nextState"> 
<StateTimer>valveTime</StateTimer> 
<StateOutputActions> 
<OutputAction action="rewardPortValve">valve_open</OutputAction> 
</StateOutputActions> 
<StaceEvents> 
<TimerEvent timer="stateTimer" eventname="stateExpired" /> 
</StateEvents> 
</BeadlState> 
</BeadlStates> 
<Bead1lStateTransitions> 
<Bead1StateTransition from="startState" to="nextState" eventname="rewardPortin" label="" /> 
<Bead1lStateTransition from="nextState" to="end" eventname="stateExpired" label="" /> 
</BeadlStateTransitions> 
</BeadlTrialProtocol> 
<BeadlEditor /> 
</Bead1> 





2.2.1 BeadlArguments element 


The BeadlArguments element defines a container for additional BeadlArgument elements 
(see section 2.2.1.1). Only one BeadlArguments container is allowed within a 
BeadlTrialProtocol node and it can have zero or more BeadlArgument child elements. 


2.2.1.1  BeadlArgument element 
The BeadlArgument elements define values that are being passed to a single trial and allow 
to update certain values on a trial-by-trial basis. This way the experiment’s control system 
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(in case of Bpod, either the running MATLAB or Python instance) can update or prede- 
fine those values. 


A BeadlArgument element has the following two attributes: 


e name: Defines reference (variable name) to be accessed 


The name attribute of a BeadlArgument is the actual variable name in the controlling 
instance. In the example above it is defined as valveTime. 


e type: Defines the data type of the argument 
Valid values for the type attribute of a BeadlArgument are logical, numerical or string. 


2.2.2 HardwareSettings element 


The HardwareSettings element defines a container for hardware specific properties and 
settings of the current task description. Its main purpose is to group the connection def- 
initions and settings for physical inputs (e.g. ConnectionMapping elements) and to define 
the controlling hardware for the automatic code generation process. To accomplish this, 
the following attributes are defined: 


e hardware: Defines the name of the used control hardware 


The hardware attribute plays a main role for the automatic code generation since it 
defines which code generator needs to be used. In the example above the attribute 
is set to Bpod 


e version: Defines the version/revision of the control hardware used 


The version attribute also impacts the process of the code generation. In the above 
example this attribute is set to version 0.5 of the Bpod hardware revision. For this 
particular hardware, the different revisions have different APIs that needs to be 
considered in the process of generation the hardware-specific code. 


e lang: Defines the programming language for interfacing the control hardware 


The lang attribute defines the programming language for the automatic code gen- 
eration. In case of the above example, the Bpod programming language could ei- 
ther be MATLAB or Python. 


2.2.2.1 ConnectionMapping element 

A ConnectionMapping element maps a certain resource of the experiment-controlling 
hardware to a specifier in the task description. Furthermore, it defines the type of the 
resource and enables to predefine specific values of the resource. The following attributes 
are defined for each ConnectionMapping element: 


e name: Defines the specifier within the BEADL protocol for the mapped resource 


The name attribute defines the specifier for the mapped resource and acts like a 
variable name or reference in certain other BEADL elements. In the above exam- 
ple the attribute is set to rewardPort for the defined ConnectionMapping element. 


resource: Defines the mapped hardware resource 


The resource attribute defines the name of the used resource of the control hard- 
ware and depends on the defined attributes of the HardwareSettings element. In 
the example above the used resource is Port1 of the Bpod hardware. For revision 
0.5 of the Bpod hardware the available resources are: 


o Behavior ports Port1 — Ports (photogate, LED, valve) 

o BNC inputs BNC1In and BNC2In 

o BNC outputs BNC10ut and BNC20ut 

o Wire input terminals Wire1In, Wire2In, Wire3In, Wire4In 

o Wire output terminals Wire10ut, Wire2Out, Wire30ut, Wire4out 

o Serial communication (UART) output interface Serial1 and Serial2 


o Timer resources GlobalTimer1, GlobalTimer2, GlobalTimer3, GlobalTimer4, 
GlobalTimer5 
type: Specifies the type of resource that is mapped 


The type attribute specifies what kind of resource is mapped and depends on the 
hardware used for controlling the experiment. For revision 0.5 of the Bpod hard- 
ware the types of resources are: 


o port: Specifying a behavioral port (consists of a photogate, an LED and a 
driver for a solenoid valve) 


o binaryInput: Specifying a binary input (BNC1In, BNC2In, Wire1In, Wire2In, 
Wire3In, Wire4In) 


o binaryOutput: Specifying a binary output (BNC10ut, BNC20ut, Wire10ut, 
Wire2Out, Wire30ut, Wire40ut) 


o serialOutput: Specifying a serial interface (Serial1 and Serial2) 


o globalTimer: Specifying a hardware timer resource (GlobalTimer1 — Global- 
Timer5) 


Furthermore, the ConnectionMapping element defines two child elements: 


Value: Defines an initialization value for the resource 


The Value child element of a ConnectionMapping element can be used to define an 
initialization value for the mapped resource. For a timer resource that can be the 
amount of time the timer has to run. The content of the Value element can be 
passed by a BeadlArgument (see section 2.2.1.1). A ConnectionMapping element can 
have zero or one Value element. 


Dependency: Defines an additional dependency for mapping the resource 


The Dependency child element of a ConnectionMapping element can be used to define 
if an additional dependency is specified for mapping this resource. Since 
Dependency elements are not limited to ConnectionMapping elements, their 
description can be found in their corresponding section (see section 2.2.7 for more 
details). 


In the BEADL example above there is only one ConnectionMapping specified that maps the 
behavioral port Port1 of the Bpod to the specifier rewardPort. 


2.2.3. BeadlInputs element 


The BeadlInputs element defines a container for all the input entities used within the 
protocol to trigger state transitions. In the current implementation of BEADL, these are 
the only inputs that are physically available through the controlling hardware (e.g. Bpod) 
but the concept also allows to introduce so-called “virtual inputs” which will be imple- 
mented in future versions of BEADL. Only one BeadlInputs container is allowed within a 
BeadlTrialProtocol node and it can have zero or more child elements. 


2.2.3.1 HardwareInput element 

HardwareInput elements define specifiers and type information for all the physical inputs 
used in a task, and are linked to a ConnectionMapping (see section 2.2.2.1). By introducing 
this layered structure, the process of describing inputs (and actions — see section 2.2.4.1) 
becomes more organized in case the physical hardware connection has multiple grouped 
individual inputs that needs to be referred to, and simplifies compatibility between dif- 
ferent hardware platforms. The HardwareInput element defines the following attributes: 


e name: Defines a name of this individual input that can be referred to 


The name attribute of a HardwareInput element acts like a reference in a BEADL de- 
scription and can be used in a state’s event section. In the example above the name 
for the input is specified as rewardPortPoke. 


e connection: Links the input specification to a physical entity 


The connection attribute of a HardwareInput element links this element to the hard- 
ware input entity. If the entity is a group of multiple input and output channels 
(e.g. a behavioral port), the dot-notation can be used to refer to the desired input 
channel of the corresponding ConnectionMapping element. In other words, the spec- 
ified value of the connection attribute must be either a valid name of a defined 
ConnectionMapping, or a member of it in case of grouped channels. In the example 
above the input is linked to the photogate of the behavioral port, indicated by link- 
ing the input to the poke member of the rewardPort instance. 


e type: Defines the type of the input 


The type attribute of a HardwareInput element defines the valid values an input can 
have. In theory that is already defined through the linked ConnectionMapping 
element, but the type attribute defines the valid values for the event definition in 
later defined Bead1State elements. The valid values for the type attribute depend 
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on the used hardware. In the example above the type in/out is defined for the 
HardwareInput element rewardPortPoke. Valid values for the type attribute when 
using the Bpod platform are: 


o in/out for the photogate-based poke detection of a behavioral port 
o ttl for binary input channels (BNC and WirelIn inputs) 


2.2.3.2 VirtualInput element 
VirtualInput elements extend the current concept of inputs in a BEADL description and 
will be implemented in a future version. 


2.2.4 BeadlActions element 


The BeadlActions element defines a container for all the output entities that are used 
within the protocol and which trigger actions to be executed by the controlling hardware. 
In the current implementation of BEADL, these are only inputs that are physically avail- 
able through the controlling hardware (e.g. Bpod) but the concept also allows to introduce 
so-called “virtual actions” which will be implemented in future versions of BEADL. Only 
one BeadlActions container is allowed within a Bead1TrialProtocol node and it can have 
zero or more child elements. 


2.2.4.1 HardwareAction element 

Like the way HardwareInput elements (see section 2.2.3.1) define the actual physical inputs 
in a behavior task description with BEADL, HardwareAction elements define the physical 
outputs in a BEADL description. The HardwareAction element defines the following at- 
tributes: 


e name: Defines a name of this individual action that can be referred to 


The name attribute of a HardwareAction element acts like a reference in a BEADL 
description and can be used in a state’s event section. In the example above the 
names for the two defined inputs are rewardPortLED and rewardPortValve. 


e connection: Links the action specification to a physical entity 


The connection attribute of a HardwareAction element links this element to the 
hardware output entity. If the entity is a group of multiple input and output chan- 
nels (e.g. a behavioral port), the dot-notation can be used to refer to the desired 
output channel of the corresponding ConnectionMapping element. In other words, 
the specified value of the connection attribute must be either a valid name of a 
defined ConnectionMapping or a member of it in case of grouped channels. In the 
example above the outputs are linked to the led and the reward valve driver of the 
behavioral port, indicated by linking the outputs to the led and valve members of 
the rewardPort instance. 


e type: Defines the type of the output action 


The type attribute of a HardwareAction element defines the valid values that can be 
assigned to a defined output. This value predefined through the linked 
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ConnectionMapping element, but the type attribute specifies the valid values for the 
output action definition in later defined Bead1State elements. The valid values for 
the type attribute depend on the hardware used. In the example above the types 
for the two defined actions are led and valve. Valid values for the type attribute 
when using the Bpod platform are: 


o led for the led attached to a behavioral port 

o valve for the valve driver of a behavioral port 

o ttl for binary output channels (BNC and WireOut outputs) 

o serial for the serial communication interfaces (Seriall and Serial2) 
o timer for the global timer resources (GlobalTimerl — GlobalTimerS) 


2.2.4.2 VirtualAction element 

Like the VirtualInput elements mentioned in section 2.2.4.2 VirtualAction elements will 
be introduced in future BEADL versions to extend the current concept of actions in a 
BEADL description. 


2.2.5 BeadlStates element 


The Bead1States element acts as a container for the actual state definitions of the behavior 
task (see section 2.2.5.1). Only one BeadlStates container is allowed within a 
BeadlTrialProtocol node and it must have at least one child element of the type 
BeadlState. 


2.2.5.1 Bead1lState element 

The Beadl1state element defines the fundamental entity in the state-machine-like BEADL 
description. A BeadlState element defines multiple different subsequent elements but 
only one attribute. The name attribute acts as a reference — especially in the definition of 
the transitions between the states. That is why a unique name based purely on ASCII 
characters must be used. The name end is not allowed since this is a pre-defined state 
name to indicate the end of the trial. In the example above two states are defined: 
startState and nextState. 


2.2.5.1.1 StateTimer child elements 

The StateTimer element defines the maximum duration of a given state. The value of this 
element will be interpreted in seconds. If the timer elapses a special timer event will be 
triggered (see section 2.2.5.1.8.1). If the state lists that event under its StateEvents element, 
a transition to another state can be caused by the StateTimer. If the state does not list the 
corresponding event, the StateTimer element does not have an impact on the state. The 
value of this element can also be passed by a Bead1Argument. In the example above the first 
state does not specify a StateTimer since no associated event is listed under the 
StateEvents element. However, the second state uses a defined StateTimer element, set 
by a BeadlArgument element, to open a reward valve for a specific amount of time. 


2.2.5.1.2 StateOutputActions child elements 

The StateOutputActions element act as a container for all the output actions triggered 
during the state. Only one StateOutputActions element is allowed within a Beadl1State 
element and it can have zero or more OutputAction elements. 


2.2.5.1.2.1 OutputAction elements 

The OutputAction element defines an action that is being generated when the state 
machine enters the current state (Moore machine). To refer for example to an output 
channel, the element’s action attribute must be used. When referencing to a 
HardwareAction, the actual value of the OutputAction element must meet the type 
definition of the HardwareAction element (see section 2.2.4.1). In the example above the 
first state defines an action associated with the HardwareInput rewardPortLeED. Since this is 
of type led, the valid values for the OutputAction element are on, off and the 8-bit values 
from 0 to 255. The second state defines an OutputAction associated with the HardwareInput 
rewardPortValve. Since this is of type valve, only the values valve_open and valve_closed 
are being interpreted by the current BEADL implementation for the used Bpod version. 


2.2.5.1.8 StateEvents child elements 

Like the StateOutputActions element, the StateEvents element acts as a container for all 
the input events for the current state. There must only be one StateEvents element de- 
fined within a BeadlTrialProtocol node and it can have zero or more event child ele- 
ments. 

2.2.5.1.3.1 TimerEvent elements 

TimerEvent elements can either be triggered by a local state timer or by a global timer 
property. To refer to a timer resource, the timer attribute must be used. Furthermore, a 
value must be defined for the eventname attribute. This attribute together with the name 
attribute of the current state and the state to which this event causes a transition to form 
a tuple in the Beadl1StateTransitions list (see sections 2.2.6 and 2.2.6.1). In the example 
above, only in the second state a TimerEvent element is defined and linked to the state’s 
internal timer. If this timer elapses the event with the eventname stateExpired will be trig- 
gered 


2.2.5.1.8.2 ExternalEvent elements 

ExternalEvent elements implement the sensitivity of the task protocol towards external 
input channels of the used experiment-controlling hardware. The reference towards a 
HardwareInput element is handled through the source attribute. Since the referred 
HardwareInput element has an associated type attribute, the valid values of the 
ExternalEvent elements are defined through this. Like in the description of the TimerEvent 
elements, the specified eventname attributes facilitate the correct mapping of the 
transition between states. 


2.2.5.1.8.8 ArgumentEvent elements 

ArgumentEvent elements are different to other events since they do not strictly happen 
within a trial. They constitute a formal way for changing the structure of the state 
machine on a trial-by-trial basis based on values of a BeadlArgument updated before each 
trial. The following attributes are defined for ArgumentEvent elements: 


e argument: Specifies the name of the BeadlArgument element 


The argument attribute of ArgumentEvent elements acts like a reference to a 
BeadlArgument element in a BEADL description. 


e comparison: Defines the comparison operator for the BeadlArgument element 


The comparison attribute of ArgumentEvent elements specifies the used operator for 
comparing the content of the referred BeadlArgument element. Valid values for this 
attribute are less, less equal, equal, greater equal, greater, and not equal. 


e value: Defines the value to which the BeadlArgument element is compared to 


The value attribute of ArgumentEvent elements defines the value the referred 
BeadlArgument element is compared to. The content of this attribute must meet the 
BeadlArgument element’s data type specified in its type attribute (see section 2.2.1.1). 


e eventname: Name of the event to be referred to in the state transition 


The eventname attribute together with the name attribute of the current state and the 
state to which this event causes a transition to form a tuple in the 
Bead1StateTransitions list (see sections 2.2.6 and 2.2.6.1). 


2.2.6 BeadlStateTransitions element 


The Bead1StateTransitions element acts as a container for the definition of transitions 
between the different states of a behavior task triggered by the different events defined 
previously (see section 2.2.6.1). Only one BeadlStateTransitions container is allowed 
within a BeadlTrialProtocol node and it must have at least one child element of the type 
Bead1StateTransition. 


2.2.6.1 BeadlStateTransition element 

A BeadlStateTransition element defines the transition from one state to another when a 
certain event happens. For this, a unique tuple is defined based on the following attrib- 
utes: 


e from: Defines the origin state of this transition 
The from attribute of Bead1StateTransition elements defines the starting or origin 
state of the transition and must be a valid and unique state name defined as a 
Bead1State element. 

e to: Defines the target state of this transition 
The to attribute of Bead1StateTransition elements defines the ending or target 
state of the transition and must be a valid and unique state name defined as a 
Bead1State element. 

e eventname: Defines the event that causes the transition from origin to target state 


The eventname attribute of a Bead1StateTransition element defines the event of the 
originating state that causes the transition to the targeting state. 
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BeadlStateTransition elements define an additional attribute label which content can be 
used to specify a descriptor for the transition, e.g. in a graphical representation. 

In the example protocol implementation above, two Bead1StateTransition elements are 
defined. The first one specifies the transition from the state named startState to the state 
named nextState in case a rewartPortin event happens. The second element specifies the 
transition from the state named nextState to the terminating state named end in case a 
stateExpired event happens 


2.2.7 Dependency element 


Dependency elements play a special role in a BEADL task description since they can be 
defined as child elements for different element types. A Dependency element allows the 
corresponding parent element to be added to the task description if the condition in the 
Dependency element is met. A Dependency element has only one attribute called type which 
can be used to distinguish between different dependency types. In the current version, 
only the BeadlArgument dependency type is defined using a previously defined 
BeadlArgument element (see section 2.2.1.1) as the input for the dependency. In addition to 
the type attribute, a Dependency element defines the following three child elements: 


e Reference: Defines a reference to some other instance for the dependency 


The Reference child of a Dependency element can be used to define the source of 
the dependent character of the parent element. In case of a BeadlArgument depend- 
ency type, the value of Reference must be the name of a BeadlArgument element. 


e Condition: Defines the condition that the dependency must meet 


The Condition child of a Dependency element defines the logical condition that the 
Dependency element must meet to become effective. For the BeadlArgument depend- 
ency type, this element can have the values less, less equal, equal, greater equal, greater, 
and not equal. 


e Value: Defines a value for the defined condition 


The Value child of a Dependency element defines a value for the condition of this 
dependency. The content of the Value element itself can be a Bead1lArgument again. 


<?xml version="1.0" encoding="UTF-8"?> 
<Beadl version="0.1"> 
<BeadlTrialProtocol name="DependencyExample" startState="InitTrial" numberOfTrials="Inf"> 
<BeadlArguments> 
<BeadlArgument name="trialType" type="numerical" /> 
</BeadlArguments> 
<HardwareSettings hardware="Bpod" version="0.5" lang="MATLAB"> 


<ConnectionMapping name="correctPort" resource="Porti" type="port"> 
<Value /> 
<Dependency type="BeadlArgument" > 
<Reference>trialType</Reference> 
<Condition>equal</Condition> 
<Value>1</Value> 
</ Dependency> 
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To illustrate the usage of a Dependency element, the above code snippet shows how the 
ConnectionMapping can be extended to add a condition to the mapping of an input speci- 
fier to a hardware resource. In the example, the specifier correctPort will only be linked 
to the Port1 resource if the content of the previously defined Bead1lArgument trialType is 
equal to 1. 


2.3  BeadlEditor element 


So far, the Bead1Editor element is just a place holder for a future graphical editor. 


12 


